Alpha's M2 Mode - The Mode For Modula-2 Programmers

Help for M2 Mode Version 3.7.3                  af EHTZ 13/Nov/2001

This M2 mode is designed for Alpha 7.4.2 or newer

Maintainer: Andreas Fischlin, <andreas.fischlin@ito.umnw.ethz.ch> 
Systems Ecology, ETH Zurich, Switzerland 
<http://www.ito.umnw.ethz.ch/SysEcol>


	___________________________________________________________

	  	About M2 Mode

	___________________________________________________________

This mode is for programming in Modula-2 using e.g. the RAMSES or MacMETH 
shell.  M2 mode allows to comfortably switch between a shell, i.e.  the 
application running the compiler, linker, your programs etc. and Alpha.  
Compiler errors are shown in the status bar (bottom of screen) and with 
CTRL-E you can locate easily any faulty location(s) in your source code.
	
Modula-2 for the Macintosh is available as FreeWare, courtesy ETH Zurich as 
part of the software packages RAMSES or MacMETH, (see links below).

To really make good use of this mode see topics "# Working with Modula-2 Files", 
"# Keyboard bindings", "# Typing and Templates", "# Looking Up Information", and
<<gotoMark "M-Button and {}-Button">>.  
Have fun!


 The mode comes preinstalled in Alpha (V >= 7.5) or download the latest M2
mode from

<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware.html#RAMSES_Extras>

or       <ftp://ftp.ucsd.edu/pub/alpha/>

Mail bug reports or feature wishes to: <RAMSES@ito.umnw.ethz.ch>


 Get a Modula-2 language system for free from
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware.html#RAMSES> 

or (smaller, but less powerful)
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware.html#MacMETH>  


 Other links possibly of interest:
<http://www.ito.umnw.ethz.ch/SysEcol>
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware2.html>

___________________________
(*) RAMSES is an acronym for Research Aids for Modelling and Simulation of 
Environmental Systems 
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/RAMSES/RAMSES_Welcome.html>

RAMSES is based on MacMETH "Fast Modula-2 Language System for the Apple 
Macintosh" by N.  Wirth et al., the inventor of Pascal, Modula-2, and 
Oberon, Swiss Federal Institute of Technology Zurich (ETHZ), Switzerland.
<http://www.ethz.ch>























	___________________________________________________________

	  	Working with Modula-2 Files

	___________________________________________________________

Alpha will automatically switch into "Modula-2 Mode" (abbreviated "M2") if
you open a file with the extension .MOD, .mod, .DEF, .def, .PRJ, .prj,
*.DTF, *.MOD.MSTR, *.M2 or *.m2.  It also switches into the M2 mode if
press CTRL-0, a global key binding, or when Alpha is newly launched from a
Modula-2 shell.  Then the M2 mode opens all so-called working files as
listed in the file "err.ALPHA".  The file "err.ALPHA" is searched in the
folder in which the Modula-2 shell, i.e. the RAMSES or MacMETH shell,
resides you have specified during initial automatic or explicit
configuration of the M2 mode.  The Modula-2 shell is the application which
can execute the Modula-2 compiler, linker, debugger, and your own so-called
subprograms.  They can all be executed from within the same application,
since RAMSES and MacMETH feature a dynamic linking-loader!  BTW, for the
record only: In the late eighties MetroWorks purchased from the Swiss
Federal Institute the source code license for the MacMETH Modula-2 compiler
and the "Dialog Machine" to offer a commercial Modula-2 development system. 
Then they built CodeWarrior.  AFAIK MetroWerks no longer offers this
Modula-2 development system.  However, the MacMETH language system or its
superset RAMSES are still available as freeware, courtesy the Siwss Federal
Institute of Technology Zurich ETHZ <http://www.ethz.ch>.

____________________________________________________________________________
IMPORTANT: Here some basics which gets you started.  Press CTRL-0 (zero)
and Alpha opens the current work file(s).  If none opens (maybe the case if
neither MacMETH nor RAMSES present), choose "File -> New" and force M2 mode
(choose M2 from lower right pop-up menu button in status bar) and choose
menu "M2 -> Templates -> New Program MODULE".  Save it and press CTRL-1 to
switch to the Modula-2 shell.  In the latter compile with CMD-C and if the
compiler reports errors press CMD-E (for AlphaEdit) to reenter Alpha. 
Alpha will then automatically open for you all files lately compiled
(implicit CTRL-0) and will display any possibly detected compiler errors
(implicit first CTRL-E).  CTRL-E lets you scan through all errors in your
source code(s) in a circular fashion.  That all really works as described,
you need to properly configure your setup "# Installation". 
The mode must be properly installed in Alpha and you should have a
functioning Modula-2 shell present, which has AlphaEdit installed and
associated with CMD-E (AlphaEdit is in directory M2Tools).  By default the
latter is the case only in the so-called big RAMSES shell (activate it by
the student proof keyboard shortcut CMD-SHIFT-CAPSLOCK-B (B for big).
____________________________________________________________________________

As soon you are in the M2 mode an additional menu, named M2, is inserted in
the menubar.  It offers essential functions and the support for programing
in Modula-2 via menu commands.  For keyboard shortcuts (key bindings) see
below ("# Keyboard bindings").  The latter make actually all the
difference!

Hint: If you start from scratch with menu command "File -> New" or with any
other file having a different extension and you wish to activate the M2
mode, you can always force the M2 mode by using the "Mode Pop-up" menu
(button in lower right corner of the message/status bar).

Related topics: "# Configuration and Customization", "# Installation",
"# Keyboard bindings", "# Typing and Templates", "# Looking Up Information",
<<gotoMark "M-Button and {}-Button">>, "# Known Bugs - Problems and Solutions"
(should you encounter difficulties).













	___________________________________________________________

	  	Typing and Templates

	___________________________________________________________

In M2 mode Alpha examines every keystroke and expands automatically your typing.
For example: FOR<Space bar>i<Tab>0<Tab>9<Tab> will give you

	FOR i := 0 TO 9 DO
	  |<- cursor will be placed here
	END;(*FOR*)
	
and the cursor will be placed just below FOR, indented by the proper amount
of spaces.  Note, the mode writes deliberately no real tabs, since this
makes the code more readable in the debugger.  You may configure the number
of spaces indents use (see also "# Configuration and Customization"). 
Instead of the last Tab you could have also used Shift^Return as an
alternative.  Typing

	for<Cmd^Tab>...  

works similarly.  Check it out for yourself.

Note, the key <Return> breaks not only the current line, but does also
indent on the next new line intelligently according to the current,
Modula-2 language specific context.  Only <Shift^Control^Return> will break
the line at the current position without any indentation.  For more nifty
features offered by the M2 mode, e.g. check out <Option^Return> or
<Command^Return>, see topic "# Keyboard bindings".

<Command^Tab> (or ESC followed by space bar) will expand the current word,
if there is an equivalent in the Modula-2 reserved word list or if you have
defined a word (typically an identifier) in your program text which begins
with what you have just typed.  The latter is searched above and then
below.  Note, the M2 mode still supports CMD-TAB, given you have turned off
or changed MacOS' default application switching (see also "Alpha Manual").

For example, typing PROC<Command>^<Tab> (or PROC<ESC><Space bar>) will result in 
PROCEDURE and typing a further blank will automatically trigger the insertion of 
the entire PROCEDURE template, e.g. resulting in

	PROCEDURE MyProcedure;
	BEGIN (* MyProcedure *)
	END MyProcedure;

after having entered in the dialog the procedure's name 'MyProcedure'.

HINTS: There is a diffference between typing IF<Space bar> vs. if<Space
bar>, or if<Command>^<Tab>, check it out.  Did you know, once you've
written an entire definition module, M2 offers automatic IMPLEMENTATION
MODULE generation?  Use menu command "M2 -> Def To Mod" when DEFINITION is
front window.  Note also the big templates for entire modules, see menu
commands "M2 -> Templates -> New xyz MODULE".  In case you don't like a
particular feature of these large templates, sorry, but you gonna have to
modify the code of the file "m2Templates.tcl" yourself and to reinstall it
afterwards.  Look for the procedures 'defBODY', and 'modBODY'.  (see also
"# Installation" and "# Configuration and Customization"). To customize the 
completions edit "m2Completions.tcl" and correspondingly "M2 Tutorial.M2".

For all details on this topic see the Completions Tutorial
(menu "Config -> Mode Prefs -> Completions Tutorial") or "M2 Tutorial.M2". 












	___________________________________________________________

	  	M-Button and {}-Button

	___________________________________________________________

The M2 mode supports the {}- and M-button of the upper right window corner 
(thanks to Tom Featherstone!).  

 M-Button ((Cmd^click title bar)

The M-Button lists so-called structural marks, modules, and all procedures 
and of course function procedures. There are several options (modes) which 
let you control the actual appearance of the generated list. You can list:

  - Main structural marks
  - Section structural marks (nested within main structural marks)
  - Modules (including local ones)
  - Procedures

Use the preferences, i.e. choose menu "Config -> Mode Prefs -> Preferences..." 
(or F12) to define what is listed by the M-button. Normally items are listed in 
order of occurrence, but flag 'sortListedItems' lets you sort the list alphabe- 
tically.  Structural marks stand out.  Main ones are preceeded by a '', section 
ones by a '-'.  Indentations of procedures and modules represent Modula-2 scopes. 
If flag 'Mark Sees Comments' is off, procedures within comments are not marked.

Structural marks are particular comments in your source code. 
Main marks start with '(*#####', end with '#####*)', and are made by Ctrl^3. 
Section marks start with (*====, end with =====*), and are made by Ctrl^4. Flag 
'Boxed Section Marks' determines the format of section marks.  Ex.: To get a 
main structural mark select some text like <My Header>, press Ctrl^3 and you get

	(***********************)        
	(*##### My Header #####*)        
	(***********************)	   

Note, not selected parts of the current line or possibly present remainders
of an older mark are discarded and replaced by the new mark!!


 {}-Button
The {}-button lists all Modula-2 procedures and function procedures in 
alphabetical order.  The formal parameter list of each procedure is 
analyzed and shown in an abbreviated form after its name within curly 
braces.  Value parameters are listed with a '', variable (name) parameters 
with a 'v'.  Function procedures are always listed with curly braces plus 
the symbolic representation of the returned value as ': v'.  Ex.: 

	PROCEDURE AParlessProcedure;
	PROCEDURE VarProc (VAR c: Complex; n: INTEGER; VAR y: ARRAY OF REAL);
	PROCEDURE LightIsOn(): BOOLEAN;
	PROCEDURE Func(x: REAL; VAR y: Complex): REAL;
  
The {}-button lists above code as 	  	  

	AParlessProcedure
	Func {v}: v
	LightIsOn {}: v
	VarProc {vv}  

Related topics: "# Configuration and Customization", "# Keyboard bindings"












	___________________________________________________________

	  	Looking Up Information

	___________________________________________________________

The M2 mode supports the looking up of marked information. Simply 
Command^Doubleclick a particular identifier, typically you click on the 
identifier of a particular procedure, and its declaration is searched in other 
files like definition modules or so-called quick reference files.  The file in 
which the declaration has been found is then opened and positioned such that the 
found mark is displayed and the cursor placed at the procedure heading.

 Command^Doubleclick on a procedure identifier
_______________________________________________

First the current file is searched and the cursor is placed at its declaration  
in case it is a local one.  Otherwise, i.e. if the procedure is an imported one, 
all currently open files and then finally all quick reference files are searched 
and opened (read only mode) at the corresponding procedure declaration.


 Control^Command^Doubleclick on a procedure identifier
______________________________________________________

The same as Command^Doubleclick, but the corresponding partner module is also 
searched and opened.  For instance, if you currently work with the 
IMPLEMENTATION MODULE of a module, the corresponding DEFINITION MODULE is also 
positioned such that the procedure becomes visible; or vice versa.  With the 
keyboard shortcut Control^Option^O you can conveniently flip back and forth 
between the two files. If the procedure is not local, the DEFINITION MODULE of 
the library module from which the procedure has been imported is opened 
(read only mode) at the position of the declaration.

Modules are searched at these places: 

1) within the current folder

2) if the current folder ends with ".MOD" within a folder ending with ".DEF" 
   (but otherwise the same path)

3) if the current folder ends with ".DEF" within a folder ending with ".MOD" 
   (but otherwise the same path)

4) within folder docuFolder (customizable via menu "Config > Current Mode > 
   Preferences" (F12)) assuming within this folder reside folders named M2, DM, 
   MW, or AuxLib wich contain again folders ending with ".DEF"

Note: Searches can only succeed if the file has been marked with option 
"List procedures" (see topics <<gotoMark "M-Button and {}-Button">> and 
"# Configuration and Customization"); it's recommended to check "Auto Mark". 


Related topics: "# Keyboard bindings" (for keyboard shortcuts)
"# Installation", and "# Configuration and Customization"



















	___________________________________________________________

	  	Keyboard bindings

	___________________________________________________________

	  	  Launching shell & Compiler errors
CTRL-0		 Open recently compiled work object file(s) and jump to 1st error
CTRL-e      	 Jump to next compiler error (as detected by last compilation)
CTRL-1		 Launch MacMETH or RAMSES Shell (depends on current configuration)
		 and trigger a program execution (e.g. in RAMSES) (needs System 7)
CTRL-2           Like CTRL-1 but without triggering program execution

	  	  Modula-2 place holders & Moving around
CTRL-g		 Jump to the next Placeholder ( = comment of form (*. text .*) )
CTRL-OPTION-g	 Jump to the previous Placeholder (also CTRL-SHIFT-g)
CTRL-HOME/END	 Jump to the beginning/end of the file
CTRL-LEFT/RIGHT	 Backward/Forward one word

	  	  Selections
CTRL-SHIFT-DOWN	 Select entire current line; hint: to expand SHIFT-cursorUP/DOWN 
CTRL-SHIFT-s	 Select surrounding comment (if present)            *)

	  	  RETURN key
RETURN           Breaks line & indents intelligently, e.g. if after BEGIN, inserts 
                 new line and "indentation amount" of spaces (amount configurable) 
SHIFT-RETURN     Jumps to end of current line (no break) and then performs RETURN 
CMD-RETURN       Like SHIFT-RETURN but never indents in a language specific way
CTRL-RETURN      Resume position before last jump caused e.g. by TAB, CMD-RET etc. 
SHIFT-CTRL-RET   Breaks line and does no indentation
OPTION-RETURN    New line and move cursor down (same position within line) 
CMD-SHIFT-RET    Open new line above current
CMD-CTRL-SH-RET  Skip next line and perform SHIFT-RETURN 

	  	  TAB key
TAB		 Move cursor in a context specific way to next insertion point of 
		 interest, e.g. as given by a bullet. Otherwise make indentation 
OPTION-TAB       Force indentation (similar as TAB, but ignore subsequent bullets)
CTRL-OPTION-TAB  Forces insertion of an actual TAB char (use only if you have to)
SHIFT-TAB        Remove indentation spaces (configurable)
CTRL-SHIFT-TAB   Adjust current line's indentation to that of non-white line above 
CMD-SHIFT-TAB    Same as CTRL-SHIFT-TAB but line below
		
	  	  Editing helpers
CMD-TAB/ESC-' '	 Triggers completion of what you've begun to type "M2 Tutorial.M2"
CTRL-r/OPT-]	 Shift lines in selection to the right (by indentation spaces)
CTRL-l/OPT-[	 Shift lines in selection to the left (by half indentation spaces)
CTRL-BACKSPACE	 Kills the entire current line
OPT-BACKSPACE	 Kills the current line from the cursor position to the end
CTRL-m           Minimize space surrounding cursor position to a single space
CTRL-j           Jump to end of line & join it with next & minimize white-space 
CTRL-OPT-SH-f    List content of a directory in a new window 
CMD-SHIFT-f      Filter entire source for current conditional compiler flag 
CTRL-OPTION-o    Open other lib. module if in same folder (DEF->MOD or MOD->DEF)
CMD-OPTION-n     Show path and file name of top window in status bar (global)

	  	  Modula-2 comments
CTRL-c           Comment selection (using configurable prefixString, suffixString)
CTRL-OPTION-c	 Uncomment selection (revert CTRL-c; also CTRL-SHIFT-c)
CTRL-k		 Comment selection to a place holder of form (*. selection .*)
CTRL-OPTION-k	 Uncomment selected place holder (also CTRL-SHIFT-k)
CTRL-a		 Wrap comment (configurable right margin) to form:  (*
                                                                      text 
                                                                    *)
CTRL-SHIFT-a	 Wrap selected Text; top left char in selection is left margin

These shortcuts are similar to the ones of MEdit (see RAMSES software package) or
MPW. MEDIT users, simply think: "Command is now control". 

Related topics: "# Typing and Templates", "M2 Tutorial.M2", 
"# Working with Modula-2 Files"











	___________________________________________________________

	  	Installation

	___________________________________________________________

As of Alpha 7.5 the M2 mode forms part of the standard Alpha release. 
There is no need to install the M2 mode anymore (albeit the mode is still
available as a separate package from
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware2.html>).

However, note, a smooth collaboration between the M2 mode and your Modula-2
development system requires to observe a few rules.  Notably, it is
recommended to have the home directory of Alpha to reside in the same
directory where the RAMSES folder, or the MacMETH folder, respectively,
resides.  In most cases this will already do.  In particular, if Ctrl^1
from within Alpha as well as Cmd^E from within the RAMSES or MacMETH shell
switches smoothly between the two applications back and forth, your
installation seems to be fine (see also "# Working with Modula-2 Files").  
In all other cases, please read on.

	  	 Modula-2 Development Environment Configuration

If you enter the M2 mode and you get some alerts telling you that the mode
had troubles finding some expected files or information, you need to alter
slightly your current configuration.  These warnings or error messages try
to help you and don't imply there is something wrong with the mode. 
Instead, fix your installation and the benefit is a smoothly working
programing environment at all times.  In this context you should understand
the following points:

	  	 	Configuring Alpha 

 The M2 mode is designed to closely collaborate with a so-called Modula-2
shell.  This is either the RAMSES shell or the MacMETH shell (Note, you
need a Modula-2 shell in order to compile any Modula-2 source code).  When
you launch for the first time the M2 mode, it will inspect your Macintosh
and search for one of these shells (priority: 1st RAMSES, 2nd MacMETH). 
Then it will try to remember where they reside or remind you of the fact
that it failed to do so, for instance because they are absent from your
computer system.  Note, the M2 mode makes sense fully only if it can
collaborate with a Modula-2 shell.  Hence it will warn you if it could not
successfully locate a Modula-2 shell.
 
 If the Modula-2 compiler detected some source code errors, it won't
display them.  It informs you only wether it encountered some errors or
not.  That's where the M2 mode from Alpha comes in handy.

 The M2 mode can open and display compiler errors in the source code.  For
instance the command Ctrl^0 (global key binding) tries to open the
so-called working object (see also "# Working with Modula-2 Files").  In
case there was a compilation error this command will also jump to the first
error location and display the appropriate error message in the status bar
at the bottom of the screen.  Ctrl^E jumps to the next error etc.  (file
after file, in a loop).  However, for this behavior the M2 mode needs
possibly lots of information (possilby hundred of files with thousands of
errors).  Wether it can find it depends on your current configuration of
the Modula-2 development environment.

 The M2 mode expects to find information about the current working object
in the same directory where the current Modula-2 shell resides.  This
information means the names of the lately compiled files and possibly
encountered compiler errors (see note below).  More precisely, since you
might have several Modula-2 shells on your system, e.g. RAMSES and MacMETH,
the M2 mode searches at any time only in the shell directory it is
currently associated with.  Simply use the menu command 
"M2 -> Configure Launching" to specify with which Modula-2 shell you 
wish the mode to collaborate.  Use this command, should you not be happy
with the current settings, e.g. if you wish to switch between the RAMSES
and the MacMETH shell (Of course, alternatively, you may also edit the mode
preferences (F12) and there modify the item "M2_shell Name", cumbersome!).

    Note: The working object is either a single file or consists of a set of
    files.  In the first case it is a Modula-2 program module (extension .MOD). 
    In the second case the work object consists of many source code files,
    forming an entire project (listed in a file with extension .PRJ).  This may
    consist of many library modules, i.e. DEFINITION (extension .DEF) and
    IMPLEMENTATION plus program modules (extensions .MOD).

    To really know all, note: Compiler errors are stored in the binary file
    "err.DAT".  Each time you use the compiler, regardless of the Modula-2
    shell from where you launch it, the compiler generates a new file "err.DAT"
    in the same directory where the calling shell resides.  The name of the
    files compiled lately are listed in the text file "err.ALPHA".  This file
    is generated by the utility "AlphaEdit".  AlphaEdit is a little prelinked
    Modula-2 subprogram stored in directory M2Tools within the RAMSES or
    MacMETH folder.  Error messages to be displayed in the status bar are
    stored in the simple text file "ErrList.DOK", again in directory M2Tools
    (<<M2::openErrListFile>>).

 For your convenience, the M2 mode can listen to Apple events sent to it
by another application, e.g. the RAMSES or MacMETH shell.  It understands a
single command, i.e. open the current work object.  It executes the same
procedure as does the global key binding Ctrl^0.  Typically there is rarely
need to press Ctrl^0, since the menu command "Edit (Alpha)..."  in the
RAMSES or "AlphaEdit" in the MacMETH shell sends such a command to Alpha,
where the M2 mode should pick it up and execute it.

	  	 	Configuring RAMSES or MacMETH 

Alas, having Alpha to open working objects as described above does NOT yet
mean that your installation is really fine.  This is because the Modula-2
shell you currently use needs also to know where Alpha is (or with which
you wish to work).  This is where the recommendation matters to have Alpha,
RAMSES, and MacMETH reside in the same directory.

 When you get compiler errors while compiling from within the RAMSES or
MacMETH shell the compiler will tell you about this fact.  In order to edit
the source, remember, ALWAYS and ONLY use the menu command "Edit
(Alpha)..."  from the RAMSES or "AlphaEdit" from the MacMETH shell (Cmd^E). 
NEVER simply switch to Alpha by other means, e.g. via the Finder's
application menu etc.  Otherwise you won't be able to display the compiler
errors!  Why?

 The menu command "Programing -> Edit (Alpha)..."  from the big RAMSES
shell actually executes the M2 tool "AlphaEdit".  This is a little Modula-2
subprogram, which does all you need to switch to Alpha for error display
and editing.  More precisely, it reads the file "User.Profile" to read the
name and location of Alpha, in order to launch the application Alpha and
bring it to the foreground later on.  Then it generates the file
"err.ALPHA" and sends the "open work object" command (Apple event) to Alpha
(Avoid to have more than one Alpha running in such a situation).  This
works also if Alpha si currently not running ad needs first to be launched. 
Finally Alpha is brought to the foreground, where it should open the
working object (one or more files) and jump to the source location of the
first compiler error encountered.  Ctrl^E will get you to the next error
etc. This is the normal behavior when the installation is fine, i.e. the 
RAMSES shell finds Alpha at its actual location on your computer.

 Should you see any error messages instead of what is describeda above,
simply open the file "User.Profile" within the RAMSES or MacMETH folder and
edit the path and file name of the Alpha you wish to use.  Search for
section "Alias" where you should have an entry similar to this (all quotes 
etc. exactly as shown below):

"Alias"
  'Edit2'   is   ' MEdit 1.80'  
  'Alpha'   is   '::Alpha :Alpha'

Note, above example assumes again you have Alpha's directory 'Alpha ' in
the same parent directory as where your Modula-2 shell resides.  Your file
system structure is similar to this, the recommended setup! 

                   /-----\_________
                   | parent folder |
                   -----------------
                  /        |        \
                /          |          \
              /            |            \
       /---\_____      /---\_____      /---\_____
       | Alpha  |     | MacMETH |     | RAMSES  |
       -----------     -----------     -----------

(Note, the relative path '::Alpha :' is going first one level "upwards"
then into directory 'Alpha ').  This flexible mechanism allows you also to
choose among different Alphas, e.g. to use "Alpha 68k" instead of "Alpha",
should you work on an 68K Mac.  IMPORTANT: Then you will need to edit the
text file "User.Profile" in any case!

You can find even more on this topic, e.g. hints on how to customize the 
menu of the MacMETH shell, at
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/RAMSES/READ_ME.RAMSES_Extras.html>
or in the file " READ to AUTOINSTALL M2".  This is available at 
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware2.html> as 
part of the separately available M2 mode package (row "Alpha editor").

	  	 Manual (Re)Installation

In Alpha version 7.x and higher simply double-click file "OPEN-TO-INSTALL" and
perform an easy installation and follow all recommendations.  That's all!  
  
You may obtain the M2 mode also separately from Alpha, as part of the 
"RAMSES Extra" release from 

<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware.html#RAMSES_Extras>
 
or

<ftp://ftp.ito.umnw.ethz.ch/pub/mac/RAMSES/>

or only the mode from

<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware2.html>

or

<ftp://ftp.ucsd.edu/pub/alpha/>

All this software is freeware, courtesy ETH Zurich, Switzerland 
<http://www.ethz.ch>.

For links to get a Modula-2 language system (including compiler, loading-linker, 
debugger, skeleton source code, huge libraries etc.) see topic 
"# About M2 Mode".

Once you have installed the M2 mode and you restart Alpha, Alpha will 
prompt you to configure your Modula-2 environment as explained under 
topic "# Configuration and Customization". 

To learn about how to use your installation, see at least topics 
"# Working with Modula-2 Files", "# Keyboard bindings", 
and "# Typing and Templates".


	  	 Deinstallation

To deinstall choose menu "Config -> Packages -> Uninstall Some Packages..." 
and select mode M2 from the flip menu.  This will remove all involved 
files and restore Alpha to the state as if M2 mode would never have been 
installed (Note, removes ALL configuration info!). 






	___________________________________________________________

	  	Configuration and Customization

	___________________________________________________________

The first time you activate the M2 mode, it will try to configure itself by
searching the desktop database for the presence of a RAMSES or MacMETH
shell.  The purpose is to establish the links between the Modula-2 shell
running the compiler, e.g. the MacMETH or RAMSES shell.  The M2 mode can
display compiler errors properly in your source code only if the mode's
settings match exactly the location of the Modula-2 shell you are using. 
Once configured, you may then easily jump back and forth between the
Modula-2 shell and Alpha via THE two essential keyboard shortcuts, i.e.
CMD-E and CTRL-1 (see also "# Working with Modula-2 Files",
"# Keyboard bindings", and "# Installation").

 Use menu command "M2 -> Configure Launching" to configure the use of a
particular Modula-2 shell.
	"M2 -> Configure Launching" lets you select the shell to which 
the shell launching commands (CTRL-1, CTRL-2) will transfer, and optionally
to choose the file which contains the messages which help you to interpret
the compiler generated error codes ("ErrList.DOK" in folder "M2Tools",
residing in the same folder where you find the MacMETH or RAMSES shell). 
"ErrList.DOK" is needed for displaying readable messages at the bottom in
the status bar when you press CTRL-E while searching for error locations in
your currently open Modula-2 working file.  Note, this command is
automatically executing at very first M2 mode activation.
   
 Use menu command "Config -> Mode Prefs -> Preferences..."  (or F12)
	"Config -> Mode Prefs -> Preferences..."  (or F12) lets you edit 
all settings of the M2 mode while the mode is active.  The mode specific
core settings are characterized by prefix "M2_ ...".  Partly their values
are also configurable via the mode's menu M2.  This is now only the case
for m2_errListDOK, m2_shellName (see above), in Alpha < 7.x this is also
the case for a few other variables (see below)).

To obtain best results recommended settings are all flags on except for these:
- Auto Continue Comment      off    (M2 F12) - "Fatal" for free format Modula-2
- Backup 	                 off    (M2 F12) - creates a mess (IMHO)
- Mark Sees Comments         off    (M2 F12) - slows down marking considerably
- Sort Listed Items          off    (M2 F12) - rarely of use
- Smart Cut Paste            off    (M2 F12) - Was always a buggy Alpha feature
To obtain best results it is recommended to set global Alpha settings as follows:
- Backup 	                 off    ("Config -> Preferences -> Backups")
- Emacs keyboard navigation  off    ("Config -> Preferences -> Features...")

Other recommendations:
- Set "Docu Folder" to the folder "Docu" within the RAMSES folder or 
Cmd-Double-Clicks respectively Ctrl-Double-Clicks won't have the desired effect!


 To use completions, i.e. keyboard shortcut <Command^Tab>, the MacOS
default settings for application switching may get into your way.  An easy
fix is to customize your MacOS by choosing menu "Help --> Help Center" in
the Finder and search for "Application switching".  There click onto
"switching between open programs" and "Help me modify the keyboard
shortcuts".  Turn the feature off or use another shortcut to free
<Command^Tab> to be used by the M2 mode.

 Editing Prefs.tcl: 
Open prefs.tcl (see Alpha's menu "Config -> Mode Prefs -> Edit Prefs File" 
(or even "Global") and add your optional customizations.  This techinque is
of particular importance if you use a pre 7 Alpha.  E.g. add this line

	set defaultFont Programmer

for having that useful font ready for your Modula-2 programming (the font
is available as part of the "RAMSES Extra" release,
<http://www.ito.umnw.ethz.ch/SysEcol/SimSoftware/SimSoftware.html#RAMSES_Extras>
see also "# Installation").

 Customizing templates: If you don't like any of the templates you gonna
have to modify them in the files "M2Completions.tcl" and correspondingly
"M2 Tutorial.M2" or "m2Templates.tcl".  Especially you may wanna
modify the procedures 'defBODY', or 'modBODY' in "m2Templates.tcl".

 Use menu command "M2 -> Configure M2 Mode" (available only in Alpha < 7.x)
	"M2 -> Configure M2 Mode" lets you enter your name used by defaults 
in module templates, to set tab spaces (shift right, shift left
respectively) and other parameters specific to the M2 mode.

Related topics: "# Installation", 
"# Known Bugs - Problems and Solutions", 
"# Typing and Templates", and <<gotoMark "M-Button and {}-Button">> 





	___________________________________________________________

	  	Known Bugs - Problems and Solutions

	___________________________________________________________

   
 Mode M2 3.7.x        See also "# Testing History" for more details!
 -------------

  Under MacOS 9.x you crash your system when you try to switch from 
   MacMETH or RAMSES shell to Alpha. Remedy: Please upgrade to latest MacMETH 
   or RAMSES.                 fixed in MacMETH >=3.2.7 or RAMSES 3.0.1 >=b5 

  Completions won't work when you press Cmd^Tab. Instead you end up in 
   another application. You have the default MacOS application switching
   active. See topic "# Configuration and Customization" for hints 
   on how to fix this.

  While writing comments you get additional, unwanted '(*' at the begin
   of each line. You should immediately turn off, i.e. uncheck the check box
   "Auto Continue Comment" by menu "Config -> Preferences -> Electrics"! 
   This feature is not only meaningless or a nuisance, but is dangerously
   error-prone in a free-format, nested comment syntax as featured by Modula-2
   (all code becomes a comment).
   
  You are using several Modula-2 shells at the same time, which reside not 
   in the same folders.  Alpha opens working files only when launched from
   one shell, but not if launched from the other, newly used one. Explanation: 
   Mode M2 can support only one shell at a time. You have to use menu 
   "M2 -> Configure Launching" to get a new shell communicating with Alpha
   properly again, of course at the expense of the cooperation with the old one.

  Oddly jagged source code when looked at from within the symbolic 
   debugger of MacMETH or RAMSES.  You're source code probably contains 
   horizontal tab characters (ASCII 11C).  Fix: Select all and choose menu 
   command "Text -> Tabs To Spaces".  Note, M2 mode deliberately avoids 
   inserting horizontal tabulations into the source code (e.g.  pressing key 
   TAB in M2 mode inserts only blanks).  However, many predefined Alpha 
   routines behave differently in this respect.  In particular you should also 
   refrain from inserting tabs in your source code, e.g.  by calling menu 
   command "Text -> Spaces To Tabs".

 Mode M2 3.6.x and older versions
 --------------------------------

  The menu command "Wrap Text" (Cntrl^Shift^A) fails. Remedy: Run 
   anywhere first "Wrap Comment" (Cntrl^A), then try again "Wrap Text".
   
  You are using the MacMETH shell and Alpha opens the Modula-2 working files
   only when launched, but afterwards no more.  Explanation: The MacMETH shell 
   is not high level event aware.  Remedy: Either make the shell high level 
   event aware (using ResEdit, resource 'SIZE' or use RMSMacMETH shell from 
   "RAMSES Extras"; disadvantage: the shell ignores shut downs and needs to be 
   quit manually) or press Ctrl^0 each time you switch to Alpha.  The latter 
   is the only means to open Modula-2 working files in case you are using a 
   MacOS older than System 7, regardless of the shell (MacMETH, RMSMacMETH, or 
   RAMSES) you are using.     fixed in MacMETH >=3.2.6 or RAMSES 2.2.3 >=b26 

 Mode M2 3.2.x and older versions
 --------------------------------
  Slow entering into M2 mode. Fix: Disable copyRing (or leave it on all
   the time) while in mode M2 "Config Prefs > Menus and Features..." and 
   uncheck copyRing in 2nd dialog "Select features for mode M2". 

  AlphaLite 6.5.2 wrongly reports "Your Preferences file 'Prefs.tcl contains 
   an error" while closing windows.  Remedy: Ignore or use big Alpha

  Sometimes Alpha won't open the most recent M2 work file(s), whatever 
   you do in the RAMSES shell.  Simply throw away the files err.ALPHA and
   token.ALPHA in the folder where the RAMSES (or MacMETH) shell resides
   and proceed; that usually helps to get you going again.   fixed in V >= 1.0

Related topics: "# Installation", "# Configuration and Customization", and
"# Testing History".

af ETHZ  24/Sep/2001




	___________________________________________________________

	  	Testing History

	___________________________________________________________

M2 mode 3.x tested with Alphas: 

6.5.2      fine, but Alpha 7.x is REALLY recommended!
7.0p2      not recommended 
7.0p5      fine
7.1b1      not recommended 
7.1b2      fine 
7.1b3      don't work well 
...        ...
7.1b5      see above 
7.1b6      fine 
7.1b7      not recommended
7.1b8      recommended!
7.1b10     works after trashing of  "System Folder:Preferences:Alpha-v7", 
7.1fc1     same as for 7.1b10 or after adding Johand Linde's code at end of 
           alpha::findAllExtensions, then its fine. Wait, not recommended, 
           since file sets don't work properly
7.1fc2     fine 
7.1fc3     fine 
7.1fc3-5   not tested
7.1fc6     fine 
7.1pre     fine
7.1        fine
7.1p2      fine
7.1p3      fine
7.1p4      fine (but requires M2 Mode >= 3.1.7)
7.1.5      recommended (but requires M2 Mode >= 3.1.7)
7.1.6      don't use it
7.1.7      fine
7.1.8      fine
7.2b1      fine
7.2b2      fine
7.2b3      fine
7.2b4      fine
7.2fc3     fine (but requires M2 Mode >= 3.2.0 for proper installation)
7.2fc4     fine (but requires M2 Mode >= 3.2.0 for proper installation)
7.2fc5     fine (but requires M2 Mode >= 3.2.0 for proper installation)
7.2fc6     fine (but requires M2 Mode >= 3.2.0 for proper installation)
7.2fc7     fine (but requires M2 Mode >= 3.2.0 for proper installation)
7.2fc8     fine (but requires M2 Mode >= 3.2.0 for proper installation)
7.2fc9     fine (but requires M2 Mode >= 3.2.4 for full working)
7.2fc10    fine (but requires M2 Mode >= 3.2.4 for full working)
7.2fc11    fine (but requires M2 Mode >= 3.2.4 for full working)
7.2        fine (but requires M2 Mode >= 3.3 and a non HFS+ startup disk)
7.2.1b1-3  don't use if you work on a HFS+ startup disk machine
7.2.1b4-9  fine (even on HFS+ startup disks and requires M2 Mode >= 3.3)
7.2.1b10   fine (even on HFS+ startup disks and requires M2 Mode >= 3.3)
7.2.2fc2-8 fine if M2 Mode >= 3.3b3
7.2.2      fine
7.3        fine
7.3-7.4b14 fine
7.4b17     fine
7.4b19     fine
7.4fc1-7   fine (fc5 not recommended)
7.4		   recommended 
7.4.1	   even better 
7.4.2	   highly recommended 
7.5a2      M2 mode is now released as part of Alpha (is buggy)
7.5a3      M2 mode needs improvements
7.5b1      M2 mode 3.7.0 needs improvements
7.5b2      M2 mode 3.7.1, also Vince happened to use an older m2Mode.tcl,
           works but needs more improvements
7.5b3      M2 mode works fine except for Help menu


See also "# Known Bugs - Problems and Solutions"
